home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / a_utils / perl / prl-dscr.el < prev    next >
Lisp/Scheme  |  1993-07-25  |  14KB  |  453 lines
  1. ;; perl-descr.el -- one-line information on a perl symbol
  2. ;; SCCS Status     : @(#)@ perl-descr.el    1.8
  3. ;; Author          : Johan Vromans
  4. ;; Created On      : Thu Jun 28 17:06:26 1990
  5. ;; Last Modified By: Johan Vromans
  6. ;; Last Modified On: Thu May 20 13:24:10 1993
  7. ;; Update Count    : 108
  8. ;; Status          : Released
  9. ;;
  10. ;; Purpose of this package:
  11. ;;
  12. ;;   This file defines the function 'describe-perl-symbol, which
  13. ;;   displays a one-line information on a perl symbol.
  14. ;;   
  15. ;;   Based on 'describe-lisp-symbol' and others.
  16. ;;   Hacked for Perl by Johan Vromans <jv@mh.nl>
  17. ;;
  18. ;; Installation instructions
  19. ;;
  20. ;;   Byte-compile and place perl-descr.elc in your emacs lisp library.
  21. ;;
  22. ;; Usage instructions:
  23. ;;
  24. ;;   Add to your .emacs:
  25. ;;
  26. ;;     (autoload 'describe-perl-symbol "perl-descr"
  27. ;;               "One-line information on a perl symbol" t)
  28. ;;
  29. ;;   Bind it to your favorite key, e.g. (from .emacs):
  30. ;;
  31. ;;     (setq perl-mode-hook 
  32. ;;           (function (lambda ()
  33. ;;              (local-set-key "\eOQ" 'describe-perl-symbol))))
  34. ;;
  35. ;; Known bugs:
  36. ;;
  37. ;;    The information is a bit terse.
  38. ;;    The function does a good job at finding the current perl symbol
  39. ;;    around point, but perl has a VERY weird syntax...
  40. ;;
  41. ;; LCD Archive Entry:
  42. ;; describe-perl-symbol|Johan Vromans|jv@mh.nl
  43. ;; |One-line information on a perl symbol.
  44. ;; 93/05/20|1.8||
  45.  
  46. (defvar perl-doc-buffer "*perl-doc*"
  47.   "Where the documentation can be found.")
  48.  
  49. (defun perl-symbol-at-point ()
  50.   "Get the closest Perl symbol to point, but don't change your
  51. position. Has a preference for looking backward when not
  52. directly on a symbol."
  53.  
  54.   (let ((perl-wordchars "a-zA-Z0-9_") start end symbol)
  55.           
  56.     (save-excursion
  57.  
  58.       ;; first see if you're just past a symbol
  59.       (if (eobp)
  60.       (if (not (bobp))
  61.           (backward-char 1))
  62.     (if (looking-at "[] \t\n[{}()]")
  63.         (progn
  64.           (skip-chars-backward " \n\t\r({[]})")
  65.           (if (not (bobp))
  66.           (backward-char 1)))))
  67.  
  68.       (if (looking-at (concat "[$%@]?[" perl-wordchars "]"))
  69.       (progn
  70.         (skip-chars-backward perl-wordchars)
  71.         (setq start (point))
  72.         ; Get identifier. Include leading $ % @ to find things like
  73.         ; @ARGV and %ENV .
  74.         (if (string-match "[$%@]" (char-to-string (preceding-char)))
  75.         (setq start (1- start))
  76.           (forward-char 1))
  77.         (skip-chars-forward perl-wordchars))
  78.  
  79.     ;; else a symbol?
  80.       (progn
  81.         (setq start (point))
  82.         (if (looking-at "[$@][^ \n\t]") ; special variable
  83.         (forward-char 1)
  84.           (if (string-match "[$@]" (char-to-string (preceding-char)))
  85.           (setq start (1- start))))
  86.         (forward-char 1)))
  87.       (buffer-substring start (point)))))
  88.  
  89. (defun describe-perl-symbol (symbol)
  90.   "Display the documentation of SYMBOL, a Perl operator."
  91.   (interactive
  92.     (let ((fn (perl-symbol-at-point))
  93.       (enable-recursive-minibuffers t)
  94.       val args-file regexp)
  95.       (setq val (read-from-minibuffer
  96.           (if fn
  97.               (format "Symbol (default %s): " fn)
  98.             "Symbol: ")))
  99.       (if (string= val "")
  100.       (setq val fn))
  101.       (setq regexp (concat "^" (regexp-quote val) "\\([ \t([/]\\|$\\)"))
  102.  
  103.       ;; get the buffer with the documentation text
  104.       (set-buffer (get-buffer-create perl-doc-buffer))
  105.       (if (= (buffer-size) 0)
  106.       (progn
  107.         (set-buffer (get-buffer-create perl-doc-buffer))
  108.         (insert
  109. "# @(#)@ perl-descr.el 1.8 - describe-perl-symbol [Perl 4.036]
  110. !    Logical negation.    != Numeric inequality.    !~ Negated pattern match or substitution.
  111. !=    Numeric inequality.
  112. !~    Search pattern, substitution, or translation (negated).
  113. $!    If used in a numeric context, yields the current value of errno. If used in a string context, yields the corresponding error string.
  114. $\"    The separator which joins elements of arrays interpolated in strings.
  115. $#    The output format for printed numbers. Initial value is %.20g.
  116. $$    The process number of the perl running this script. Altered (in the child process) by fork().
  117. $%    The current page number of the currently selected output channel.
  118. $&    The string matched by the last pattern match.
  119. $'    The string following what was matched by the last pattern match.
  120. $(    The real gid of this process.
  121. $)    The effective gid of this process.
  122. $*    Set to 1 to do multiline matching within a string, 0 to assume strings contain a single line. Default is 0.
  123. $+    The last bracket matched by the last search pattern.
  124. $,    The output field separator for the print operator.
  125. $-    The number of lines left on the page.
  126. $.    The current input line number of the last filehandle that was read.
  127. $/    The input record separator, newline by default.
  128. $0    The name of the file containing the perl script being executed. May be set
  129. $1..    Contains the subpattern from the corresponding set of parentheses in the last pattern matched.
  130. $:    The set of characters after which a string may be broken to fill continuation fields (starting with ^) in a format.
  131. $;    The subscript separator for multi-dimensional array emulation. Default is \"\\034\".
  132. $<    The real uid of this process.
  133. $=    The page length of the current output channel. Default is 60 lines.
  134. $>    The effective uid of this process.
  135. $?    The status returned by the last backtick (``) command, pipe close or system operator.
  136. $@    The perl error message from the last eval or do @var{EXPR} command.
  137. $ARGV    The name of the current file used with <> .
  138. $[    The index of the first element in an array, and of the first character in a substring. Default is 0.
  139. $\\    The output record separator for the print operator.
  140. $]    The perl version string as displayed with perl -v.
  141. $^    The name of the current top-of-page format. See also $^D, $^F, $^I, $^P, $^T, $^W, $^X
  142. $^D    The value of the perl debug (-D) flags.
  143. $^F    The highest system file descriptor, ordinarily 2.
  144. $^I    The value of the in-place edit extension (perl -i option).
  145. $^P    Internal debugging flag.
  146. $^T    The time the script was started. Used by -A/-M/-C file tests.
  147. $^W    True if warnings are requested (perl -w flag).
  148. $^X    The name under which perl was invoked (argv[0]).
  149. $_    The default input and pattern-searching space.
  150. $`    The string preceding what was matched by the last pattern match.
  151. $|    If set to nonzero, forces a flush after every write or print on the currently selected output channel. Default is 0. The following variables are always local to the current block:
  152. $~    The name of the current report format.
  153. %    Modulo division.    %= Modulo division assignment.
  154. %=    Modulo division assignment.
  155. %ENV    Contains the current environment.
  156. %INC    List of files that have been require-d or do-ne.
  157. %SIG    Used to set signal handlers for various signals.
  158. &    Bitwise and.    && Logical and.
  159. &&    Logical and.    &&= Logical and assignment.
  160. &&=    Logical and assignment.
  161. &=    Bitwise and assignment.
  162. *    Multiplication.    ** Exponentiation,
  163. **    Exponentiation.
  164. *NAME    Refers to all objects represented by NAME. *NAM1 = *NAM2 makes NAM1 a reference to NAM2.
  165. +    Addition.    ++ Auto-increment    += Addition assignment.
  166. ++    Auto-increment (magical on strings).
  167. +=    Addition assignment.
  168. ,    Comma operator.
  169. -    Subtraction.    -- Auto-decrement.    -= Subtraction assignment.
  170. --    Auto-decrement.
  171. -=    Subtraction assignment.
  172. -A    Access time in days since script started.
  173. -B    File is a non-text (binary) file.
  174. -C    Inode change time in days since script started.
  175. -M    Age in days since script started.
  176. -O    File is owned by real uid.
  177. -R    File is readable by real uid.
  178. -S    File is a socket .
  179. -T    File is a text file.
  180. -W    File is writable by real uid.
  181. -X    File is executable by real uid.
  182. -b    File is a block special file.
  183. -c    File is a character special file.
  184. -d    File is a directory.
  185. -e    File exists .
  186. -f    File is a plain file.
  187. -g    File has setgid bit set.
  188. -k    File has sticky bit set.
  189. -l    File is a symbolic link.
  190. -o    File is owned by effective uid.
  191. -p    File is a named pipe (FIFO).
  192. -r    File is readable by effective uid.
  193. -s    File has non-zero size.
  194. -t    Tests if filehandle (STDIN by default) is opened to a tty.
  195. -u    File has setuid bit set.
  196. -w    File is writable by effective uid.
  197. -x    File is executable by effective uid.
  198. -z    File has zero size.
  199. .    Concatenate strings.    .= Concatenate assignment.    .. Alternation, also range operator.
  200. ..    Alternation, also range operator.
  201. .=    Concatenate assignment strings
  202. /    Division.    /= Division assignment.    /PATTERN/io    Pattern match
  203. /=    Division assignment.
  204. /PATTERN/io    Pattern match.
  205. <    Numeric less than.    << Bitwise shift left.
  206. <<    Bitwise shift left.
  207. <=    Numeric less than or equal to.    <=> Numeric compare.
  208. <=>    Numeric compare.
  209. =    Assignment.    == Numeric equality.    =~ Search pattern, substitution, or translation.
  210. ==    Numeric equality.
  211. =~    Search pattern, substitution, or translation
  212. >    Numeric greater than.    >= Numeric greater than or equal to.
  213. >=    Numeric greater than or equal to.    >> Bitwise shift right.
  214. >>    Bitwise shift right.    >>= Bitwise shift right assignment.
  215. >>=    Bitwise shift right assignment.
  216. ? :    Alternation (if-then-else) operator.    ?PATTERN? Backwards pattern match.
  217. ?PATTERN?    Backwards pattern match.
  218. @ARGV    Contains the command line arguments for the script (not including the command name). See $0 for the command name.
  219. @INC    Contains the list of places to look for perl scripts to be evaluated by the do EXPR command.
  220. @_    Parameter array for subroutines. Also used by split if not in array context.
  221. \\0    Octal char, e.g. \\033.
  222. \\E    Case modification terminator. See \\L and \\U .
  223. \\L    Lowercase until \\E .
  224. \\U    Upcase until \\E .
  225. \\a    Alarm character (octal 007).
  226. \\b    Backspace character (octal 010).
  227. \\c    Control character, e.g. \\c[ .
  228. \\e    Escape character (octal 033).
  229. \\f    Formfeed character (octal 014).
  230. \\l    Lowercase of next character. See also \\L and \\u,
  231. \\n    Newline character (octal 012).
  232. \\r    Return character (octal 015).
  233. \\t    Tab character (octal 011).
  234. \\u    Upcase  of next character. See also \\U and \\l,
  235. \\x    Hex character, e.g. \\x1b.
  236. ^    Bitwise exclusive or.
  237. __END__    End of program source.
  238. __FILE__    Current (source) filename.
  239. __LINE__    Current line in current source.
  240. accept(NEWSOCKET,GENERICSOCKET)
  241. alarm(SECONDS)
  242. atan2(X,Y)
  243. bind(SOCKET,NAME)
  244. binmode(FILEHANDLE)
  245. caller[(LEVEL)]
  246. chdir(EXPR)
  247. chmod(LIST)
  248. chop[(LIST|VAR)]
  249. chown(LIST)
  250. chroot(FILENAME)
  251. close(FILEHANDLE)
  252. closedir(DIRHANDLE)
  253. cmp    String compare.
  254. connect(SOCKET,NAME)
  255. cos(EXPR)
  256. crypt(PLAINTEXT,SALT)
  257. dbmclose(ASSOC_ARRAY)
  258. dbmopen(ASSOC,DBNAME,MODE)
  259. defined(EXPR)
  260. delete($ASSOC{KEY})
  261. die(LIST)
  262. do { ... }|SUBR while|until EXPR    executes at least once
  263. do(EXPR|SUBR([LIST]))
  264. dump LABEL
  265. each(ASSOC_ARRAY)
  266. endgrent
  267. endhostent
  268. endnetent
  269. endprotoent
  270. endpwent
  271. endservent
  272. eof[([FILEHANDLE])]
  273. eq    String equality.
  274. eval(EXPR) or eval { BLOCK }
  275. exec(LIST)
  276. exit(EXPR)
  277. exp(EXPR)
  278. fcntl(FILEHANDLE,FUNCTION,SCALAR)
  279. fileno(FILEHANDLE)
  280. flock(FILEHANDLE,OPERATION)
  281. for (EXPR;EXPR;EXPR) { ... }
  282. foreach [VAR] (@ARRAY) { ... }
  283. fork
  284. ge    String greater than or equal.
  285. getc[(FILEHANDLE)]
  286. getgrent
  287. getgrgid(GID)
  288. getgrnam(NAME)
  289. gethostbyaddr(ADDR,ADDRTYPE)
  290. gethostbyname(NAME)
  291. gethostent
  292. getlogin
  293. getnetbyaddr(ADDR,ADDRTYPE)
  294. getnetbyname(NAME)
  295. getnetent
  296. getpeername(SOCKET)
  297. getpgrp(PID)
  298. getppid
  299. getpriority(WHICH,WHO)
  300. getprotobyname(NAME)
  301. getprotobynumber(NUMBER)
  302. getprotoent
  303. getpwent
  304. getpwnam(NAME)
  305. getpwuid(UID)
  306. getservbyname(NAME,PROTO)
  307. getservbyport(PORT,PROTO)
  308. getservent
  309. getsockname(SOCKET)
  310. getsockopt(SOCKET,LEVEL,OPTNAME)
  311. gmtime(EXPR)
  312. goto LABEL
  313. grep(EXPR,LIST)
  314. gt    String greater than.
  315. hex(EXPR)
  316. if (EXPR) { ... } [ elsif (EXPR) { ... } ... ] [ else { ... } ] or EXPR if EXPR
  317. index(STR,SUBSTR[,OFFSET])
  318. int(EXPR)
  319. ioctl(FILEHANDLE,FUNCTION,SCALAR)
  320. join(EXPR,LIST)
  321. keys(ASSOC_ARRAY)
  322. kill(LIST)
  323. last [LABEL]
  324. le    String less than or equal.
  325. length(EXPR)
  326. link(OLDFILE,NEWFILE)
  327. listen(SOCKET,QUEUESIZE)
  328. local(LIST)
  329. localtime(EXPR)
  330. log(EXPR)
  331. lstat(EXPR|FILEHANDLE|VAR)
  332. lt    String less than.
  333. m/PATTERN/iog
  334. mkdir(FILENAME,MODE)
  335. msgctl(ID,CMD,ARG)
  336. msgget(KEY,FLAGS)
  337. msgrcv(ID,VAR,SIZE,TYPE.FLAGS)
  338. msgsnd(ID,MSG,FLAGS)
  339. ne    String inequality.
  340. next [LABEL]
  341. oct(EXPR)
  342. open(FILEHANDLE[,EXPR])
  343. opendir(DIRHANDLE,EXPR)
  344. ord(EXPR)
  345. pack(TEMPLATE,LIST)
  346. package    Introduces package context.
  347. pipe(READHANDLE,WRITEHANDLE)
  348. pop(ARRAY)
  349. print [FILEHANDLE] [(LIST)]
  350. printf [FILEHANDLE] (FORMAT,LIST)
  351. push(ARRAY,LIST)
  352. q/STRING/    Synonym for 'STRING'
  353. qq/STRING/    Synonym for \"STRING\"
  354. qx/STRING/    Synonym for `STRING`
  355. rand[(EXPR)]
  356. read(FILEHANDLE,SCALAR,LENGTH[,OFFSET])
  357. readdir(DIRHANDLE)
  358. readlink(EXPR)
  359. recv(SOCKET,SCALAR,LEN,FLAGS)
  360. redo [LABEL]
  361. rename(OLDNAME,NEWNAME)
  362. require [FILENAME]
  363. reset[(EXPR)]
  364. return(LIST)
  365. reverse(LIST)
  366. rewinddir(DIRHANDLE)
  367. rindex(STR,SUBSTR[,OFFSET])
  368. rmdir(FILENAME)
  369. s/PATTERN/REPLACEMENT/gieo
  370. scalar(EXPR)
  371. seek(FILEHANDLE,POSITION,WHENCE)
  372. seekdir(DIRHANDLE,POS)
  373. select(FILEHANDLE | RBITS,WBITS,EBITS,TIMEOUT)
  374. semctl(ID,SEMNUM,CMD,ARG)
  375. semget(KEY,NSEMS,SIZE,FLAGS)
  376. semop(KEY,...)
  377. send(SOCKET,MSG,FLAGS[,TO])
  378. setgrent
  379. sethostent(STAYOPEN)
  380. setnetent(STAYOPEN)
  381. setpgrp(PID,PGRP)
  382. setpriority(WHICH,WHO,PRIORITY)
  383. setprotoent(STAYOPEN)
  384. setpwent
  385. setservent(STAYOPEN)
  386. setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)
  387. shift[(ARRAY)]
  388. shmctl(ID,CMD,ARG)
  389. shmget(KEY,SIZE,FLAGS)
  390. shmread(ID,VAR,POS,SIZE)
  391. shmwrite(ID,STRING,POS,SIZE)
  392. shutdown(SOCKET,HOW)
  393. sin(EXPR)
  394. sleep[(EXPR)]
  395. socket(SOCKET,DOMAIN,TYPE,PROTOCOL)
  396. socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)
  397. sort [SUBROUTINE] (LIST)
  398. splice(ARRAY,OFFSET[,LENGTH[,LIST]])
  399. split[(/PATTERN/[,EXPR[,LIMIT]])]
  400. sprintf(FORMAT,LIST)
  401. sqrt(EXPR)
  402. srand(EXPR)
  403. stat(EXPR|FILEHANDLE|VAR)
  404. study[(SCALAR)]
  405. substr(EXPR,OFFSET[,LEN])
  406. symlink(OLDFILE,NEWFILE)
  407. syscall(LIST)
  408. sysread(FILEHANDLE,SCALAR,LENGTH[,OFFSET])
  409. system(LIST)
  410. syswrite(FILEHANDLE,SCALAR,LENGTH[,OFFSET])
  411. tell[(FILEHANDLE)]
  412. telldir(DIRHANDLE)
  413. time
  414. times
  415. tr/SEARCHLIST/REPLACEMENTLIST/cds
  416. truncate(FILE|EXPR,LENGTH)
  417. umask[(EXPR)]
  418. undef[(EXPR)]
  419. unless (EXPR) { ... } [ else { ... } ] or EXPR unless EXPR
  420. unlink(LIST)
  421. unpack(TEMPLATE,EXPR)
  422. unshift(ARRAY,LIST)
  423. until (EXPR) { ... } or EXPR until EXPR
  424. utime(LIST)
  425. values(ASSOC_ARRAY)
  426. vec(EXPR,OFFSET,BITS)
  427. wait
  428. waitpid(PID,FLAGS)
  429. wantarray
  430. warn(LIST)
  431. while  (EXPR) { ... } or EXPR while EXPR
  432. write[(EXPR|FILEHANDLE)]
  433. x    Repeat string or array.    x= Repetition assignment.
  434. x=    Repetition assignment.
  435. y/SEARCHLIST/REPLACEMENTLIST/
  436. |    Bitwise or.    ||    Logical or.
  437. ||    Logical or.
  438. ~    Unary bitwise complement.
  439. ")
  440.         (setq buffer-read-only t)))
  441.  
  442.       ;; lookup in the doc
  443.       (goto-char (point-min))
  444.       (let ((case-fold-search nil))
  445.     (list 
  446.      (if (re-search-forward regexp (point-max) t)
  447.          (save-excursion
  448.            (beginning-of-line 1)
  449.            (let ((lnstart (point)))
  450.          (end-of-line)
  451.          (message "%s" (buffer-substring lnstart (point)))))
  452.        (error (format "No definition for %s" val))))))))
  453.